{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "nbsphinx": "hidden"
   },
   "source": [
    "This notebook is part of the `kikuchipy` documentation https://kikuchipy.org.\n",
    "Links to the documentation won't work from the notebook."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Metadata structure\n",
    "\n",
    "The [EBSD](reference.rst#kikuchipy.signals.EBSD) class stores metadata in the\n",
    "`metadata` attribute provided by HyperSpy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Exchange inline for notebook or qt5 (from pyqt) for interactive plotting\n",
    "%matplotlib inline\n",
    "\n",
    "import matplotlib.pyplot as plt\n",
    "import kikuchipy as kp\n",
    "\n",
    "\n",
    "s = kp.data.nickel_ebsd_small()\n",
    "s"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "While kikuchipy's EBSD\n",
    "([ebsd_metadata()](reference.rst#kikuchipy.signals.util.ebsd_metadata)) metadata\n",
    "structure is based on\n",
    "[HyperSpy's metadata structure](http://hyperspy.org/hyperspy-doc/current/user_guide/metadata_structure.html),\n",
    "it includes the nodes `Acquisition_instrument.Sample.Phases` to store phase\n",
    "information and `Acquisition_instrument.SEM.Detector.EBSD` for acquisition\n",
    "information. The information in these nodes are written, along with the\n",
    "patterns, to file when saving an EBSD signal in the\n",
    "[kikuchipy h5ebsd format](load_save_data.ipynb#h5ebsd)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "kp.signals.util.ebsd_metadata()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The complete list of metadata looks like this\n",
    "\n",
    "```\n",
    "    ├── Acquisition_instrument\n",
    "    │   └── SEM\n",
    "    │       ├── Detector\n",
    "    │       │   └── EBSD\n",
    "    │       │       ├── azimuth_angle [º]\n",
    "    │       │       ├── binning\n",
    "    │       │       ├── detector\n",
    "    │       │       ├── elevation_angle [º]\n",
    "    │       │       ├── exposure_time [s]\n",
    "    │       │       ├── frame_number\n",
    "    │       │       ├── frame_rate [1/s]\n",
    "    │       │       ├── gain [dB]\n",
    "    │       │       ├── grid_type\n",
    "    │       │       ├── manufacturer\n",
    "    │       │       ├── sample_tilt [º]\n",
    "    │       │       ├── scan_time [s]\n",
    "    │       │       ├── static_background (numpy.ndarray)\n",
    "    │       │       ├── version\n",
    "    │       │       ├── xpc\n",
    "    │       │       ├── ypc\n",
    "    │       │       └── zpc\n",
    "    │       ├── beam_energy [kV]\n",
    "    │       ├── magnification\n",
    "    │       ├── microscope\n",
    "    │       └── working_distance [mm]\n",
    "    └── Sample\n",
    "        └── Phases\n",
    "            └── 1\n",
    "                ├── atom_coordinates\n",
    "                │   └── 1\n",
    "                │       ├── atom\n",
    "                │       ├── coordinates (x0, y0, z0)\n",
    "                │       ├── debye_waller_factor [nm^2]\n",
    "                │       └── site_occupation\n",
    "                ├── formula\n",
    "                ├── info\n",
    "                ├── lattice_constants (a, b, c and alfa, beta, gamma) [nm and º]\n",
    "                ├── laue_group\n",
    "                ├── material_name\n",
    "                ├── point_group\n",
    "                ├── setting\n",
    "                ├── source\n",
    "                ├── space_group\n",
    "                └── symmetry\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The utility function\n",
    "[metadata_nodes()](reference.rst#kikuchipy.signals.util.metadata_nodes) returns\n",
    "the node strings for the `SEM` and `EBSD` nodes for convenience.\n",
    "\n",
    "<div class=\"alert alert-info\">\n",
    "\n",
    "Note \n",
    "\n",
    "If you regularly use information relevant to EBSD data not included in the\n",
    "metadata structure, you can request this in our\n",
    "[issue tracker](https://github.com/pyxem/kikuchipy/issues).\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sem_node, ebsd_node = kp.signals.util.metadata_nodes()\n",
    "print(sem_node, ebsd_node)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.metadata.get_item(f\"{ebsd_node}.xpc\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "nbsphinx-thumbnail": {
     "tooltip": "Where relevant microscope, detector, and sample parameters are stored with a signal and how to get and set them"
    },
    "tags": [
     "nbsphinx-thumbnail"
    ]
   },
   "outputs": [],
   "source": [
    "plt.imshow(s.metadata.get_item(f\"{ebsd_node}.static_background\"), cmap=\"gray\")\n",
    "_ = plt.axis(\"off\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## EBSD\n",
    "\n",
    "This node contains information relevant for EBSD data. All parameters can be\n",
    "set with the method\n",
    "[set_experimental_parameters()](reference.rst#kikuchipy.signals.EBSD.set_experimental_parameters).\n",
    "An explanation of each parameter is given in the method's docstring."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_experimental_parameters(xpc=5.64)\n",
    "s.metadata.get_item(f\"{ebsd_node}.xpc\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Phases\n",
    "\n",
    "This node contains information relevant for EBSD scans or simulated patterns'\n",
    "phases. All parameters can be set with the\n",
    "[EBSD](reference.rst#kikuchipy.signals.EBSD) class method\n",
    "[set_phase_parameters()](reference.rst#kikuchipy.signals.EBSD.set_phase_parameters).\n",
    "An explanation of each parameter is given in the methods' docstring."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.metadata.Sample.Phases"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "s.set_phase_parameters(info=\"Polycrystalline\")\n",
    "s.metadata.Sample.Phases"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.10"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
